{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "f48d0afd",
   "metadata": {},
   "source": [
    "# Intro"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c6faae1",
   "metadata": {},
   "source": [
    "This tutorial will show you how to use <b>FastKafkaAPI</b>, step by step.\n",
    "\n",
    "The goal of FastKafkaAPI is to simplify the use of Apache Kafka in Python inspired by FastAPI look and feel.\n",
    "\n",
    "In this Intro tutorial we'll go trough the basic requirements to run the demos presented in future steps."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3943a6d2",
   "metadata": {},
   "source": [
    "## Installing FastKafkaAPI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a04caa3f",
   "metadata": {},
   "source": [
    "First step is to install FastKafkaAPI\n",
    "\n",
    "```shell\n",
    "$ pip install fastkafka\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e99120de",
   "metadata": {},
   "source": [
    "## Preparing a Kafka broker"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9019cf73",
   "metadata": {},
   "source": [
    "Next step is to prepare the Kafka environment, our consumers and producers will need some channel of communication.\n",
    "\n",
    "!!! info \\\"Hey, your first info!\\\"\n",
    "\n",
    "    If you already have an instance of Kafka running that you can connect to for demo purposes, feel free to skip this step. \n",
    "\n",
    "To go through the tutorial, we recommend that you use dockerized Kafka brokers, if you have Docker and docker-compose installed the setup should take you no time (if we exclude the container download times).\n",
    "\n",
    "!!! warning \\\"Listen! This is important.\\\"\n",
    "\n",
    "    To be able to setup this configuration you need to have Docker and docker-compose installed\n",
    "    \n",
    "    See here for more info on <a href = \\\"https://docs.docker.com/\\\" target=\\\"_blank\\\">Docker</a> and <a href = \\\"https://docs.docker.com/compose/install/\\\" target=\\\"_blank\\\">docker compose</a>\n",
    "\n",
    "To setup the recommended environment, first, create a new folder wher you want to save your demo files (e.g. fastkafka_demo).\n",
    "Inside the new folder create a new YAML file named <b>kafka_demo.yml</b> and copy the following configuration into it:\n",
    "\n",
    "``` yaml\n",
    "version: \"3\"\n",
    "services:\n",
    "    zookeeper:\n",
    "        image: wurstmeister/zookeeper\n",
    "        hostname: zookeeper\n",
    "        container_name: zookeeper\n",
    "        networks:\n",
    "          - fastkafka-network\n",
    "        ports:\n",
    "          - \"2181:2181\"\n",
    "          - \"22:22\"\n",
    "          - \"2888:2888\"\n",
    "          - \"3888:3888\"\n",
    "    kafka:\n",
    "        image: wurstmeister/kafka\n",
    "        container_name: kafka\n",
    "        ports:\n",
    "          - \"9093:9093\"\n",
    "        environment:\n",
    "            HOSTNAME_COMMAND: \"docker info | grep ^Name: | cut -d' ' -f 2\"\n",
    "            KAFKA_ZOOKEEPER_CONNECT: \"zookeeper:2181\"\n",
    "            KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTER:PLAINTEXT,INSIDE:PLAINTEXT\n",
    "            KAFKA_ADVERTISED_LISTENERS: INTER://:9092,INSIDE://localhost:9093\n",
    "            KAFKA_LISTENERS: INTER://_{HOSTNAME_COMMAND}:9092,INSIDE://:9093\n",
    "            KAFKA_INTER_BROKER_LISTENER_NAME: INTER\n",
    "            KAFKA_CREATE_TOPICS: \"hello:1:1\"\n",
    "        volumes:\n",
    "            - /var/run/docker.sock:/var/run/docker.sock\n",
    "        depends_on:\n",
    "            - zookeeper\n",
    "        healthcheck:\n",
    "            test: [ \"CMD\", \"kafka-topics.sh\", \"--list\", \"--zookeeper\", \"zookeeper:2181\" ]\n",
    "            interval: 5s\n",
    "            timeout: 10s\n",
    "            retries: 5\n",
    "        networks:\n",
    "          - fastkafka-network\n",
    "networks:\n",
    "    fastkafka-network:\n",
    "        name: \"fastkafka-network\"\n",
    "```\n",
    "\n",
    "This configuration will start a single instance of Zookeeper, single instance of Kafka broker and create a 'hello' topic (quite enough for a start).\n",
    "To start the configuration, run: \n",
    "```shell\n",
    "$ docker-compose -f kafka_demo.yaml up -d --wait\n",
    "```\n",
    "This will start the necessary containers and wait till they report that they are Healthy. After the command finishes, you are good to go to try out the FastKafkaAPI capabilities! :confetti_ball:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4947af09",
   "metadata": {},
   "source": [
    "## Running the code"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3eb41e6f",
   "metadata": {},
   "source": [
    "After installing FastKafkaAPI and initialising the Kafka broker you can proceed to the 'First Steps' part of the tutorial. There, you will write your first Kafka client and producer apps, run them, and interact with them.\n",
    "\n",
    "You are highly encouraged to follow along the tutorials not just by reading trough them but by implementing the code examples in your own environment. This will not only help you remember the use cases better but also, hopefully, demonstrate to you the ease of use of this library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f9d16a4c",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
